<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Apache Tomcat 4 - Jasper 2 JSP Engine How To</title><meta name="author" value="Glenn L. Nielsen"><meta name="email" value="glenn@apache.org"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./../images/tomcat.gif" align="right" alt="
      The Tomcat Servlet/JSP Container
    " border="0"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 4</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top" nowrap="true"><h1>Jasper 2 JSP Engine How To</h1></td><td align="right" valign="top" nowrap="true"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<p>
<a href="#Introduction">Introduction</a><br>
<a href="#Upgrading">Upgrading</a><br>
<a href="#Configuration">Configuration</a><br>
<a href="#Production Configuration">Production Configuration</a><br>
<a href="#Web Application Compilation">Web Application Compilation</a><br>
<a href="#Using Jikes">Using Jikes</a><br>
</p>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

<p>Starting with Tomcat 4.1, Tomcat uses the Jasper 2 JSP Engine to implement
the <a href="http://java.sun.com/products/jsp/">JavaServer Pages 1.2</a>
specification.</p>

<p>Jasper 2 has been redesigned to significantly improve performance over
the orignal Jasper.  In addition to general code improvements the following
changes were made:
<ul>
<li><strong>JSP Custom Tag Pooling</strong> - The java objects instantiated
for JSP Custom Tags can now be pooled and reused.  This significantly boosts
the performance of JSP pages which use custom tags.</li>
<li><strong>Background JSP compilation</strong> - If you make a change to
a JSP page which had already been compiled Jasper 2 can recompile that
page in the background.  The previously compiled JSP page will still be
available to serve requests.  Once the new page has been compiled
successfully it will replace the old page.  This helps improve availablity
of your JSP pages on a production server.</li>
<li><strong>Recompile JSP when included page changes</strong> - Jasper 2
can now detect when a page included at compile time from a JSP has changed
and then recompile the parent JSP.</li>
<li><strong>Ant used to compile JSP pages</strong> - The
<a href="http://jakarta.apache.org/ant/">Ant Build Tool</a> is now
used to perform JSP java source code compilation.</li>
</ul>
</p>

<p>Jasper is implemented using the servlet class
<code>org.apache.jasper.servlet.JspServlet</code>.</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Upgrading"><strong>Upgrading</strong></a></font></td></tr><tr><td><blockquote>

<p>Upgrading to Tomcat 4.1 and Jasper 2 from an earlier version of
Tomcat and/or Jasper.</p>

<p>Jasper 2 generates different java source code from Jasper 1.  You
must remove all previous class files generated for your JSP pages
from your <code>work</code> directory.</p>

<p>Jasper 2 implements JSP Custom Tag Pooling.  This can cause
JSP custom tags which are not compliant with the JSP specification to fail
or behave inconsistently.  When upgrading from a version of Tomcat earlier
than 4.1 you should test to make sure your JSP pages which use custom tags
are working correctly.</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Configuration"><strong>Configuration</strong></a></font></td></tr><tr><td><blockquote>

<p>By default Jasper is configured for use when doing web application
development.  See the section <a href="#Production Configuration">
Production Configuration</a> for information on configuring Jasper
for use on a production Tomcat server.</p>

<p>The servlet which implements Jasper is configured using init parameters
in your global <code>$CATALINA_BASE/conf/web.xml</code>.

<ul>
<li><strong>checkInterval</strong> - If development is false and reloading is
true, background compiles are enabled. checkInterval is the time in seconds
between checks to see if a JSP page needs to be recompiled. Default
<code>300</code> seconds.</li>

<li><strong>compiler</strong> - Which compiler Ant should use to compile JSP
pages.  See the Ant documenation for more information. Default
<code>javac</code>.</li>

<li><strong>classdebuginfo</strong> - Should the class file be compiled with
debugging information?  <code>true</code> or <code>false</code>, default
<code>true</code>.
</li>

<li><strong>classpath</strong> - What class path should I use while compiling
generated servlets?  By default the classpath is created dynamically based on
the current web application.</li>

<li><strong>development</strong> - Is Jasper used in development mode (will
check for JSP modification on every access)? <code>true</code> or
<code>false</code>, default <code>true</code>.</li>

<li><strong>enablePooling</strong> - Determines whether tag handler pooling is
enabled. <code>true</code> or <code>false</code>, default <code>true</code>.
</li>

<li><strong>ieClassId</strong> - The class-id value to be sent to Internet
Explorer when using &lt;jsp:plugin&gt; tags.   Default
<code>clsid:8AD9C840-044E-11D1-B3E9-00805F499D93</code>.</li>

<li><strong>fork</strong> - Have Ant fork JSP page compiles so they are
performed in a seperate JVM from Tomcat? <code>true</code> or
<code>false</code>, default <code>true</code>.</li>

<li><strong>javaEncoding</strong> - Java file encoding to use for generating
java source files. Default <code>UTF8</code>.</li>

<li><strong>keepgenerated</strong> - Should we keep the generated Java source
code for each page instead of deleting it? <code>true</code> or
<code>false</code>, default <code>true</code>.</li>

<li><strong>logVerbosityLevel</strong> - The level of detailed messages to be
produced by this servlet.  Increasing levels cause the generation of more
messages.  Valid values are <code>FATAL, ERROR, WARNING, INFORMATION,</code>
and <code>DEBUG</code>. Default <code>WARNING</code>.</li>

<li><strong>mappedfile</strong> - Should we generate static content with one 
print statement per input line, to ease debugging?
<code>true</code> or <code>false</code>, default <code>false</code>.</li>

<li><strong>reloading</strong> - Should Jasper check for modified JSPs?
<code>true</code> or <code>false</code>, default <code>true</code>.</li>

<li><strong>scratchdir</strong> - What scratch directory should we use when
compiling JSP pages? Default is the work directory for the current web
application.</li>
</ul>
</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Production Configuration"><strong>Production Configuration</strong></a></font></td></tr><tr><td><blockquote>

<p>When using Jasper 2 in a production Tomcat server you should consider
making the following changes from the default configuration.
<ul>
<li><strong>development</strong> - To enable background compilation of JSP
pages set this to <code>false</code>.</li>
<li><strong>fork</strong> - The internal JVM javac compiler used by Ant
has a known memory leak. And Ant requires that java compiles be synchronized,
i.e. only one JSP page can be compiled at a time.  Set fork to
<code>true</code> so that Ant compiles JSP pages in a seperate JVM.
This removes the synchronization of JSP page compiles and prevents
all the javac classes from being instantiated and subsequently garbage
collected by the JVM Tomcat is running in.</li>
</ul>
</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Web Application Compilation"><strong>Web Application Compilation</strong></a></font></td></tr><tr><td><blockquote>

<p>Using Ant is the preferred way to compile web applications using JSPC. 
Use the script given below to precompile a webapp:
</p>

<p>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
&lt;project name="Webapp Precompilation" default="all" basedir="."&gt; 

  &lt;target name="jspc"&gt; 

    &lt;taskdef classname="org.apache.jasper.JspC" name="jasper2" &gt; 
      &lt;classpath id="jspc.classpath"&gt; 
        &lt;pathelement location="${java.home}/../lib/tools.jar"/&gt; 
        &lt;fileset dir="${tomcat.home}/server/lib"&gt; 
          &lt;include name="*.jar"/&gt; 
        &lt;/fileset&gt; 
        &lt;fileset dir="${tomcat.home}/common/lib"&gt; 
          &lt;include name="*.jar"/&gt; 
        &lt;/fileset&gt; 
      &lt;/classpath&gt; 
    &lt;/taskdef&gt; 

    &lt;jasper2 
             validateXml="false" 
             uriroot="${webapp.path}" 
             webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml" 
             outputDir="${webapp.path}/WEB-INF/src" /&gt; 

  &lt;/target&gt; 

  &lt;target name="compile"&gt;

    &lt;mkdir dir="${webapp.path}/WEB-INF/classes"/&gt;
    &lt;mkdir dir="${webapp.path}/WEB-INF/lib"/&gt;

    &lt;javac destdir="${webapp.path}/WEB-INF/classes"
           optimize="off"
           debug="on" failonerror="false"
           srcdir="${webapp.path}/WEB-INF/src" 
	   excludes="**/*.smap"&gt;
      &lt;classpath&gt;
        &lt;pathelement location="${webapp.path}/WEB-INF/classes"/&gt;
        &lt;fileset dir="${webapp.path}/WEB-INF/lib"&gt;
          &lt;include name="*.jar"/&gt;
        &lt;/fileset&gt;
        &lt;pathelement location="${tomcat.home}/common/classes"/&gt;
        &lt;fileset dir="${tomcat.home}/common/lib"&gt;
          &lt;include name="*.jar"/&gt;
        &lt;/fileset&gt;
        &lt;pathelement location="${tomcat.home}/shared/classes"/&gt;
        &lt;fileset dir="${tomcat.home}/shared/lib"&gt;
          &lt;include name="*.jar"/&gt;
        &lt;/fileset&gt;
      &lt;/classpath&gt;
      &lt;include name="**" /&gt;
      &lt;exclude name="tags/**" /&gt;
    &lt;/javac&gt;

  &lt;/target&gt;

  &lt;target name="all" depends="jspc,compile"&gt;
  &lt;/target&gt;

&lt;/project&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<p>
The following command line can be used to run the script
(replacing the tokens with the Tomcat base path and the path to the webapp 
which should be precompiled):<br>
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
$ANT_HOME/bin/ant -Dtomcat.home=&lt;$TOMCAT_HOME&gt; -Dwebapp.path=&lt;$WEBAPP_PATH&gt;
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
</p>

<p>
Then, the declarations and mappings for the servlets which were generated 
during the precompilation must be added to the web application deployment
descriptor. Insert the <code>${webapp.path}/WEB-INF/generated_web.xml</code>
at the right place inside the <code>${webapp.path}/WEB-INF/web.xml</code> file.
Restart the web application (using the manager) and test it to verify it is 
running fine with precompiled servlets. An appropriate token placed in the
web application deployment descriptor may also be used to automatically
insert the generated servlet declarations and mappings using Ant filtering 
capabilities. This is actually how all the webapps distributed with Tomcat 
are automatically compiled as part of the build process.
</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using Jikes"><strong>Using Jikes</strong></a></font></td></tr><tr><td><blockquote>

<p>If you wish to use
<a href="http://oss.software.ibm.com/developerworks/opensource/jikes/">
Jikes</a> to compile JSP pages:
<ul>
<li>Download and install jikes. jikes must support the -encoding option.
Execute <code>jikes -help</code> to verify that it was built with support
for <code>-encoding</code>.</li>
<li>Set the init parameter <code>compiler</code> to <code>jikes</code>.</li>
<li>Define the property <code>-Dbuild.compiler.emacs=true</code> when starting
Tomcat by adding it to your <code>CATALINA_OPTS</code> environment variable.
This changes how jikes outputs error messages so that it is compatible with
Jasper.</li>
<li>If you get an error reporting that jikes can't use UTF8 encoding, try
setting the init parameter <code>javaEncoding</code> to
<code>ISO-8859-1</code>.</li>
</ul>
</p>

</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
        Copyright &copy; 1999-2009, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>